home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / amok98-106 / amok105 / english / poster < prev    next >
Text File  |  1994-05-10  |  9KB  |  198 lines
  1. ===========================================================================
  2.                      AMOK - Amiga Modula & Oberon Klub
  3.  
  4.             "Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.                Tips und Anhaltspunkte für Veröffentlichungen
  6. ===========================================================================
  7.  
  8. Introduction
  9.  
  10. AMOK welcomes also Modula-2 or Oberon programs, written by people other than
  11. the  club members, on the AMOK disks.  The aim of the PD series is to spread
  12. Modula  &  Oberon  as  far  as  possible.  Since both languages support easy
  13. exchange  of the program modules, every programmer can contribute something.
  14. The  bigger  the  module library is, the easier it is to save time and work,
  15. since  you  don't  have  to  'invent  the wheel a second time'.  If you have
  16. written  modules  which  you  think that other might have use for them, then
  17. send  them  to  AMOK.   If  it  is  possible, we will publish it in our AMOK
  18. series.   We  don't expect programs by genius', but if you want your program
  19. published, you should obey the rules below.  Like this it is guaranteed that
  20. your program is really usefull.
  21.  
  22.  
  23. 1) Criteria
  24.  
  25. As  mentioned  above we don't expect anything revolutionary, but the program
  26. should do what it is expected to do in a senseful and correct way.  A simple
  27. but  useful  module  has  got more chances, than a great project, which does
  28. often crash!
  29.  
  30.  
  31. 2) AMOK demands
  32.  
  33. The following are obligatory for all AMOK submissions:
  34.  
  35. * Each module must be supported by documentation.  Without documentation the
  36.   modules are useless for others.  There are the following possibilities for
  37.   documentation on AMOK disks:
  38.  
  39.     - documentation  in  an  extra  file  with the suffix ".dok" (the German
  40.       documentation) or ".doc" (the English one)
  41.  
  42.     - short  description of the procedures in the definition modul.  This is
  43.       all explained in 'HeaderInfo'.
  44.  
  45.   The documentation should at least contain the following information:
  46.     - meaning and function of the parameter of the procedures
  47.     - function and usage of the procedures
  48.     - meaning and returning values of the procedures
  49.     - important notes on exporting variables, constants and types
  50.     - notes on bugs (if known)
  51.     - information on limits or warnings
  52.  
  53.   If  possible  then  write  the documentation in pure ASCII code (so it can
  54.   be used with MuchMore and 'copy <file> to PRT:').
  55.  
  56. * Very   important   are   also  the  files  with  the  product  information
  57.   (".product-info")  which are specificated after the FishROM Database Draft
  58.   #5  (or  higher, changes see below!).  Without this the chance to get onto
  59.   an AMOK disk is very low.
  60.  
  61.   A  description  of  the file format is on disk (file 'Product-Info.Spec').
  62.   You  should  use English for description, but any other language is better
  63.   than nothing.
  64.  
  65.   We  have  decided  to use the .product-info format by Fred Fish.  This has
  66.   many advantages:
  67.  
  68.   - just ONE description for AMOK and Fish
  69.   - KingFisher is able to administer AMOK disks
  70.   - we can create the contents files automatically
  71.  
  72.   The format must be used as it is, but there are some changes from Draft #6
  73.   by Fred Fish:
  74.  
  75.   --> .reference  is  not  optional  for AMOK files.  It must be supplied if
  76.       there  exists  an  earlier  version  in order to create a link to that
  77.       version.
  78.  
  79.       Ex.:
  80.       --------schnipp--------
  81.       .reference
  82.       AMOK#99:DrawA5000/
  83.       1.0
  84.       --------schnapp--------
  85.  
  86.       Creates e.g. "Update to version 1.0 on AMOK #99"
  87.  
  88.   --> Source  is  not  optional.  This  string is searched for the following
  89.       keywords: Oberon, Modula, M2, Arexx. The keywords then appear directly
  90.       after the name (in brackets). Ex.:
  91.  
  92.       DrawA5000 1.1 (Oberon/Modula/Arexx)
  93.  
  94.   --> We introduced a new field: .beschreibung
  95.       This  schould  contain the description in german language.  This field
  96.       is used to generate the file 'Inhalt'.
  97.  
  98.   You  can  find  examples  on each AMOK disk (upto 103 only as 'mini-info',
  99.   which was created by ourselves).
  100.  
  101. *  The modules  should  always  have their source code with them.  Like this
  102.    other programmers are able to learn something from your program and it is
  103.    then possible to remove some bugs or one is able to configure the program
  104.    for one's needs. But there are some exceptions:
  105.  
  106.     - the  program  is really exceptional and should be patented (it must be
  107.       totally bugfree)
  108.     - the  modules  are  part  of a commercially distributed program and you
  109.       don't want others to steal parts of it
  110.     - your  programming  is  so  bad and your methods so abstruse,  that you
  111.       don't  want  to take  the risk others seeing your source code (in this
  112.       case you should think about changing to C or Assembler!)
  113.  
  114. * Definition  and  implementation  modules  should contain our module header
  115.   (see  'HeaderInfo').   This  is necessary, since the AMOK library contains
  116.   already some Megabyte.  Please stick with the format in 'HeaderInfo'.
  117.  
  118. * All  files  and  directories  should  have  icons, so that they are easily
  119.   accessible  from  Workbench.   The default tool for text files (source and
  120.   documentation) should be ':c/MuchMore'.
  121.  
  122.  
  123. 3) AMOK conventions
  124.  
  125. Please obey the following:
  126.  
  127. * If you use non standard modules for compiling then you should supply them.
  128.   Please take care that the sym-key is correct, i.e.  everything is compiled
  129.   with the same definition module.  If there are more than one version of an
  130.   imported module, then state the required one (:Imports.).
  131.  
  132. * Please  use  only  70  to  75  characters  in  the  source  code  and  the
  133.   documentation.   MuchMore  and  M2Emacs accept up to 80 characters, but if
  134.   you  print  the  text,  it  is  quite useful to have a little space on one
  135.   margin.
  136.  
  137. * Procedure,  variables,  constants  and  type names should be English.  The
  138.   same  applies  for  the  short descriptions of the procedures (see AMOK#7,
  139.   ProgInfo/StandardIDs).  You shouldn't mix English with other languages.
  140.  
  141. * If  have small demos, you can use them to easily demonstrate the functions
  142.   of  a  module.   In  most cases are test modules or other examples already
  143.   there, because they are 'side effects' of your actual program.
  144.  
  145. * Please  be  fair  about  other programmers.  PD does not mean that you can
  146.   steal  whatever you like.  If you take parts from others, then mention the
  147.   author  in  the module header or in remark lines.  If you want to use them
  148.   commercially  you  need  a  written  permission of the author.  And please
  149.   don't forget the shareware fees.
  150.  
  151.  
  152. 4) Programming guidelines
  153.  
  154. The following is not only important for AMOK disks, but should be dealt with
  155. by  all programmers.  If these information are not evident for you, then you
  156. should change your programms IMMEDIATELY!
  157.  
  158. * All programs must be programmed according to the guidelines of the ROM
  159.   Kernal Reference Manuals.
  160.  
  161.   - Amiga User Interface Style Guide ISBN 0-201-57757-7, Addison-Wesley
  162.   - Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1, Addison-Wesley
  163.   - Amiga ROM Kernel Manual: Includes & Autodocs ISBN 0-201-56773-3, A.-W.
  164.   - Amiga ROM Kernel Manual: Devices ISBN 0-201-56775-X, Addison-Wesley
  165.   - Amiga Hardware Manual ISBN 0-201-56776-8, Addison-Wesley
  166.   - The Amiga Guru Book, Ralph Babel, published by author
  167.  
  168.   - Native Developer's Update 3.1 (Examples, Debugging-Tools, Includes,
  169.                                    Autodocs)
  170.  
  171. * All  programs  must  have  an  exit,  i.e.   you  don't have to reboot the
  172.   computer and everything should be in the same state as before starting the
  173.   program.   All  devices  and  resources  must be released (deallocation of
  174.   memory, closure of windows, screens and files).
  175.  
  176. * Programs  shouldn't behave as if they were the only program in the system.
  177.   They  should  take  care  of  the  multitasking and its restrictions (e.g.
  178.   usage of devices and resources).
  179.  
  180. * All programs should work logically and shouldn't fail with false entries.
  181.  
  182. * Never expect to get all resources you need.  Programs should always have a
  183.   defined  way of exit, if e.g.  a file couldn't be opened or if there isn't
  184.   enough memory left.
  185.  
  186. * The  user interface should be standard AMIGA one (see Amiga User Interface
  187.   Style Guide).
  188.  
  189. * The programs shouldn't rely on a certain device configuration (e.g.  A500+
  190.   with 2 MB and 3 disk drives).
  191.  
  192. * It  is  important  for  future  library  modules  to  make  the procedures
  193.   reentrant.   Just  in case it makes sense to use them from different tasks
  194.   at  the  same time (in Modula it is not possible to import the same module
  195.   twice).
  196.  
  197. --- Have fun
  198.